feat!: bump @gusto/embedded-api to v2026-02-01 by jeffredodd · Pull Request #2255 · Gusto/embedded-react-sdk

jeffredodd · 2026-06-24T16:50:03Z

Summary

Upgrades the SDK from @gusto/embedded-api-v-2025-11-15 to @gusto/embedded-api-v-2026-02-01.

Every breaking change in v2026-02-01 is either:

handled by existing client-side defenses (Zod schemas, typecheck) — verified by the typecheck CI step
on an endpoint with no SDK consumer — typecheck is the contract
a server-side validation tightening that flows through the SDK's existing error pipeline (normalizeToSDKError → errorHandling.error.fieldErrors[] → inline UI render)

Breaking changes & how this PR verifies them

Legend: 🔴 = SDK code change required · ⚠️ = verify-only / test fixture update · ✅ = no impact

Status	Change	Where verified
🔴	`QueryParamSortBy` removed from `putv1companiescompanyidpayrollspayrollidprepare` op (collapsed to `string`)	Fixed in this PR: `src/components/Payroll/usePreparedPayrollData.ts` — removed the import, typed `sortBy?: string`. Typecheck CI.
✅	`SortBy` removed from `getv1companiescompanyidpayrollspayrollid` op (collapsed to `string`)	Typecheck CI — no consumer in `src/`.
✅	`GetV1CompanyFormsQueryParamSortBy` removed from `getv1companyforms` op	Typecheck CI — no consumer in `src/`.
✅	`PostV1CompaniesCompanyIdReportsEmployeesAnnualFicaWageResponseBody` removed	Typecheck CI — no consumer in `src/`.
✅	`VersionHeader` component removed (replaced by per-op `HeaderXGustoAPIVersion`)	Typecheck CI — no consumer in `src/`.
✅	`Brex` enum value removed from `Company.defaultFundingType`; new values added (`partner_disbursement`, `rtp`, `line_of_credit`)	Typecheck CI — no consumer in `src/` narrows on `'brex'`.
✅	`MigrationStatus` enum (`"success"`) removed from `PartnerManagedCompanyMigrateResponse`; replaced with new `errors[]` / `warnings[]` shape	Typecheck CI — no consumer in `src/`.
✅	`PartnerManagedCompanyMigrateRequest` body collapsed to `{}` (removed `email`, `ipAddress`, `externalUserId`; ToS signer now resolved server-side from authenticated payroll-admin user)	Typecheck CI — no consumer in `src/`.
✅	`Errors` / `Warnings` types on `partnermanagedcompanymigrationreadinessresponse` renamed to `PartnerManagedCompanyMigrationReadinessResponseErrors` / `…Warnings`	Typecheck CI — no consumer in `src/`.
✅	`PayrollCreditBlockerUnblockOptionWaitForReverseWireMetadata` collapsed to `{}` (lost `reverseWireDetailId`, `bankAccountLastFourDigits`)	Typecheck CI — no consumer in `src/`.
✅	`PeopleBatch.PartialSuccess` enum value removed	Typecheck CI — no consumer in `src/`.
✅	`EmployeeBenefit.deductionReducesTaxableIncome` required → optional (widening)	Typecheck CI — non-breaking widening.
✅	`companiesAcceptTermsOfService` / `companiesRetrieveTermsOfService` deprecated (use new `partner_managed_companies/{uuid}/terms_of_service` endpoints instead)	Typecheck CI — no consumer in `src/`. Flag in partner release notes.
✅	Self-onboarding `email` now required at the server	Trust the error pipeline — the SDK has a matching client-side Zod refinement in `src/components/Employee/Profile/shared/useEmployeeDetailsForm/buildFormSchema.ts` and existing unit tests at `buildFormSchema.test.ts:382-412` and `useEmployeeDetailsForm.test.tsx:106` already cover the gate. If the server rule were to disagree with the client refinement, the SDK's `normalizeToSDKError` → `errorHandling.error.fieldErrors[]` → inline UI render path surfaces the server message identically to the client gate.

What's in this PR

package.json + package-lock.json: dep swap (@gusto/embedded-api-v-2025-11-15 → @gusto/embedded-api-v-2026-02-01@^0.0.1).
298 src/ files: import-path rename (covers source, tests, MSW mocks under src/test/mocks/apis/, and hand-written cache-key string literals — e.g. createSdkQueryClient.ts, ApiProvider.tsx, TimeOff/*, Company/Locations/LocationForm/LocationForm.tsx).
67 sdk-app/ files: import-path rename + cache-key flips in design/prototypes/contractor-management/*.
Docs + instruction files (AGENTS.md, CLAUDE.md, src/CLAUDE.md, docs/hooks/*.md, docs/reference/index.md, docs/reference/utilities.md, docs/appendix/jobs-and-compensations.md, build/deriveEndpointInventory.ts, e2e/utils/validationErrorCollector.test.ts): version string updates.
🔴 The bare-date X-Gusto-API-Version constant flipped from '2025-11-15' → '2026-02-01' in src/contexts/ApiProvider/apiVersionHook.ts:3, plus matching assertions in apiVersionHook.test.ts (3 sites) and ApiProvider.test.tsx (1 site). Without this flip the upgrade would be a runtime no-op — types claim the new version but the SDK would still send the old one on every HTTP request.
Real type fix: src/components/Payroll/usePreparedPayrollData.ts — removed QueryParamSortBy import (no longer exported); typed sortBy?: string.
Drive-by: added language tags to 4 fenced code blocks in AGENTS.md and 2 in src/CLAUDE.md to satisfy markdownlint MD040 (pre-existing violations surfaced by the version-string sweep).

Deprecations to flag to partners

companiesAcceptTermsOfService / companiesRetrieveTermsOfService are marked @deprecated in v2026-02-01. They continue to work but partners should migrate to POST/PUT/GET /v1/partner_managed_companies/{company_uuid}/terms_of_service. The SDK does not consume either hook.
payrollCreditBlockerUnblockOptionWaitForReverseWire.reverseWireDetailId (the bare DB id) is deprecated in favor of reverseWireDetailUuid (when partners exist who use this; the SDK does not).

Test plan

All CI green (unit + e2e + typecheck + lint + build)
No remaining @gusto/embedded-api-v-2025-11-15 refs outside CHANGELOG.md / .reports/ (verified locally; grep returns empty)
Cache-namespace flip verified end-to-end (mutation under new prefix invalidates queries under new prefix — createSdkQueryClient.ts)
X-Gusto-API-Version HTTP header sends 2026-02-01 on every request (verified by apiVersionHook.test.ts and ApiProvider.test.tsx)

Acknowledgements

This PR was produced autonomously by the api-version-upgrade skill (#2243) as the canonical demonstration of the autonomous upgrade workflow.

🤖 Generated with Claude Code

mariechatfield · 2026-07-01T19:26:02Z

 import { useBase } from '../Base'
 import { retryAsync } from '@/helpers/retryAsync'

 interface UsePreparedPayrollDataParams {
  companyId: string
  payrollId: string
  employeeUuids?: string[]
-  sortBy?: QueryParamSortBy
+  sortBy?: string


actual change, and confirmed this doesn't affect us much since we've been hardcoding a string and we don't offer this as customizable options

mariechatfield · 2026-07-01T19:28:21Z

@@ -170,6 +170,6 @@ describe('ApiProvider', () => {

    const modifiedRequest = apiVersionHook.beforeRequest(mockContext, mockRequest)

-    expect(modifiedRequest.headers.get('X-Gusto-API-Version')).toBe('2025-11-15')
+    expect(modifiedRequest.headers.get('X-Gusto-API-Version')).toBe('2026-02-01')


hell yeah actual change

mariechatfield · 2026-07-01T19:28:46Z

another file that did actually change for real

Mechanical version-string sweep across src/, sdk-app/, docs/, build/, e2e/, and instruction files. package.json swap + lockfile regeneration. Rebased onto current main. Type fixups required for the bump to compile: - src/components/Payroll/usePreparedPayrollData.ts: removed QueryParamSortBy import (no longer exported from putv1companiescompanyidpayrollspayrollidprepare op; collapsed to plain string in v2026-02-01). Critical runtime sweep: - src/contexts/ApiProvider/apiVersionHook.ts: flipped CURRENT_API_VERSION = '2026-02-01' (the bare-date X-Gusto-API-Version header constant). Without this flip the upgrade would be a runtime no-op — types claim the new version but the SDK would still send the old version on every request. Test assertions in apiVersionHook.test.ts and ApiProvider.test.tsx updated to match. Drive-by: added language tags (text) to two fenced code blocks in src/CLAUDE.md to satisfy markdownlint MD040, surfaced by the version-string touch on that file. See PR description for the full breaking-change matrix and verification trail. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Regenerated via npm run derive after the v2026-02-01 bump. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jeffredodd marked this pull request as ready for review June 24, 2026 16:59

jeffredodd requested a review from a team as a code owner June 24, 2026 16:59

jeffredodd mentioned this pull request Jun 30, 2026

feat!: bump @gusto/embedded-api to v2026-06-15 #2312

Draft

5 tasks

mariechatfield reviewed Jul 1, 2026

View reviewed changes

Comment thread src/contexts/ApiProvider/ApiProvider.tsx

mariechatfield Jul 1, 2026

Copy link
Copy Markdown

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

another file that did actually change for real

serikjensen approved these changes Jul 1, 2026

View reviewed changes

jeffredodd and others added 2 commits July 1, 2026 13:44

chore: update derived files

3c05bf9

Regenerated via npm run derive after the v2026-02-01 bump. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jeffredodd force-pushed the upgrade/api-2026-02-01 branch from a471b3c to 3c05bf9 Compare July 1, 2026 20:47

jeffredodd enabled auto-merge July 1, 2026 20:50

jeffredodd added this pull request to the merge queue Jul 1, 2026

Merged via the queue into main with commit 75f7b0a Jul 1, 2026
37 checks passed

jeffredodd deleted the upgrade/api-2026-02-01 branch July 1, 2026 21:04

cursor Bot mentioned this pull request Jul 2, 2026

feat(Contractor.DocumentSigner): add contractor documents signing flow #2321

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat!: bump @gusto/embedded-api to v2026-02-01#2255

feat!: bump @gusto/embedded-api to v2026-02-01#2255
jeffredodd merged 2 commits into
mainfrom
upgrade/api-2026-02-01

jeffredodd commented Jun 24, 2026

Uh oh!

mariechatfield Jul 1, 2026

Uh oh!

mariechatfield Jul 1, 2026

Uh oh!

mariechatfield Jul 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jeffredodd commented Jun 24, 2026

Summary

Breaking changes & how this PR verifies them

What's in this PR

Deprecations to flag to partners

Test plan

Acknowledgements

Uh oh!

mariechatfield Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

mariechatfield Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

mariechatfield Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants